Skip to content

Type effect callback payloads - #48

Merged
cardmagic merged 1 commit into
mainfrom
feat/effect-payload-types
Sep 15, 2026
Merged

cardmagic merged 1 commit into
mainfrom
feat/effect-payload-types

Conversation

@cardmagic

Copy link
Copy Markdown
Owner

Effect callbacks currently force consumers to repeat an untyped payload shape. Export EffectFailurePayload, EffectSuccessPayload, and SerializedError from the root and core entries, and check the actual SQL/Cloudflare message construction against them. Payloads, normalization, retries, and delivery behavior stay unchanged.

Before:

failTurn(payload: { arguments?: Record<string, unknown> }) {
  const generation = Number(payload.arguments?.generation)
}

After:

failTurn({ arguments: original }: EffectFailurePayload<{ generation: number }>) {
  const generation = original.generation
}

The generics describe the application's declared effect contract; they do not infer or validate an independently registered handler. Ruby's corresponding RBS contract is tracked in cardmagic/solid-objects-ruby#64 and preserves its existing Ruby field names.

Validation:

  • pnpm run check and pnpm run format:check passed.
  • pnpm test: 376 passed, 21 environment-gated skips; database integration jobs run in CI.
  • Cloudflare suite: 45 passed; import/type/bundle dry-run checks passed.
  • Build and packaged-consumer smoke test passed, including root/core type imports and negative cases against the installed tarball.
  • Initial compiler failure demonstrated missing public exports. Temporary mutations to SQL success, SQL failure, and Cloudflare payload construction each produced a compiler error; restored construction compiles.
  • Added complete-envelope runtime coverage for success JSON values, undefined-to-null, absent arguments, retry exhaustion, immediate non-retryable failures, and non-Error throws.

Closes #47.

Publish shared callback and error contracts, and check the SQL and
Cloudflare envelope construction before JSON serialization. Preserve
existing payload fields, retry decisions, and normalization behavior.

Closes #47
@cardmagic

Copy link
Copy Markdown
Owner Author

@greptileai please review the current head for issue #47, including shared payload construction, compatibility, and type-test coverage.

@greptile-apps

greptile-apps Bot commented Sep 14, 2026

Copy link
Copy Markdown

Greptile Summary

This PR adds public effect callback envelope types and verifies that both SQL and Cloudflare construct payloads matching those contracts without changing runtime delivery.

  • Exports EffectFailurePayload, EffectSuccessPayload, and SerializedError through the root and browser-safe core entries.
  • Applies compile-time envelope checks to SQL and Cloudflare callback construction.
  • Adds runtime coverage for success normalization, absent arguments, retry exhaustion, terminal failures, and non-Error throws.
  • Adds source-level and installed-package type tests for positive and negative consumer contracts.
  • Documents the new callback types and backend parity.

Confidence Score: 5/5

The PR appears safe to merge; the public exports, backend envelope construction, and packaged declarations are consistently covered.

No actionable failure remains: both backends preserve their existing callback payload behavior, the core export propagates through its existing type re-export, and CI-facing tests cover runtime envelopes and installed-package typing.

Important Files Changed

Filename Overview
src/types.ts Defines the public JSON-constrained success, failure, and serialized-error callback contracts.
src/index.ts Exposes the new callback payload types from the package root.
src/repository.ts Checks SQL-backed callback envelopes and serialized errors against the new contracts without changing their values.
src/cloudflare/engine.ts Unifies Cloudflare callback construction around typed success and failure outcomes while preserving delivery behavior.
test/effect-payloads.types.ts Covers public exports, defaults, generic specialization, required fields, and JSON constraints at compile time.
scripts/release-artifact-smoke.mjs Compiles a consumer fixture against the installed tarball to verify root and core declarations.
test/outboxes.test.ts Exercises complete SQL callback envelopes across success normalization and terminal failure cases.
test/cloudflare/effect-payloads.test.ts Exercises equivalent callback envelopes and retry outcomes in the Cloudflare backend.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Actor emits effect] --> E[Durable effect or outbox]
  E --> H[Registered effect handler]
  H -->|success| S[Normalize JSON result]
  H -->|exhausted or terminal failure| F[Serialize error]
  S --> P1[EffectSuccessPayload]
  F --> P2[EffectFailurePayload]
  P1 --> C[Actor callback operation]
  P2 --> C
Loading

Reviews (1): Last reviewed commit: "feat: type effect callback payloads" | Re-trigger Greptile

@cardmagic
cardmagic merged commit 00f3929 into main Sep 15, 2026
19 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Export effect callback payload types

1 participant